/---------------------------------\
|           Bazound               |
| Sound system configuration tool |
|        Chris Bazley, 2003      |
|    Version 0.34 (07 Oct 2007)   |
\---------------------------------/
N.B. This text is best viewed at a display width of 77 columns.

-----------------------------------------------------------------------------
1   Introduction and Purpose
    ========================

  Bazound is a small configuration and diagnostic utility for the RISC OS
sound system. It may be useful to programmers writing sound software, and in
situations where programs have left the sound system in an indeterminate
state. It was written using AppBasic, a new programming aid that simplifies
the task of writing Toolbox applications in BASIC.

-----------------------------------------------------------------------------
2   Requirements
    ============

   RISC OS 3.10 or better.
   The Toolbox modules (in !System, or in ROM with RISC OS 3.6).
   The SoundDMA, SoundChannels and SoundScheduler modules (which should be
    in ROM on all RISC OS machines capable of sound).

  If any of the above facilities are unavailable then the program will fail
to load, with an error message describing the problem.

-----------------------------------------------------------------------------
3   Introduction
    ============

  Bazound provides two informational windows that can be opened from its
iconbar menu; one showing the status of the sound system in real time
('Status display...') and one that shows the current address of various
sound system components ('Components...'). These windows may also be opened
by clicking SELECT and ADJUST respectively on Bazound's iconbar icon.

  The DMA handler, channel handler and scheduler may be configured directly
via three dialogue boxes available from the 'Configure' sub-menu, or
completely reset by selecting the appropriate module name from the
'Reinitialise' sub-menu. Use these facilities with great care because you
may interfere with any software that is using the sound system.

  Changes made within dialogue boxes do not take effect in real time; to
confirm changes you must click the 'Set' button (using ADJUST rather than
SELECT if you want the dialogue box to remain open). You can make the
displayed settings reflect the current internal configuration by ADJUST-
clicking the 'Cancel' button.

-----------------------------------------------------------------------------
4   Sound status window
    ===================

  This window displays the status of various sound system parameters in real
time. It is regularly updated whilst the Wimp is idling (5 times per second
if possible).

  The display includes the current state of the DMA handler, channel handler
and scheduler. For an explanation of the meaning of the values displayed here
please refer to sections 6, 7 and 8 of this manual, which describe the
dialogue boxes for configuration of individual sound system components.

-----------------------------------------------------------------------------
5   Sound system components window
    ==============================

  This window displays the names and logical addresses of various sound
system components in real time. It is regularly updated whilst the Wimp is
idling (5 times per second, except for the 'device claimant' information).

  The 'Hardware' field at the top of this window indicates whether 16 bit
sound is supported or only 8 bit -law (as reported by SWI Sound_Mode 0). If
16 bit sound is supported then further information will be displayed. This is
derived from the flags returned in R1 (which apparently correspond to bits 5
and 6 in CMOS RAM byte 132). I don't know how reliable it is, but
paraphrasing PRM volume 5a:

- 'Master'/'slave' refers to the DAC clock vis-a-vis any external clock.
- If there is no external clock then only standard VIDC20 sample rates are
  available, whereas with an external clock additional sample rates derived
  from 44.1kHz are supported.
- If the DAC clock is master then this implies that a suitable clock
  driver is installed.

  The 'Device claimant' section of this window shows which Wimp task (if
any) currently claims exclusive ownership of the sound system. Every second,
Bazound broadcasts a DeviceClaim message to all running tasks. The device
number quoted in these broadcasts is 6.0 (major.minor), which means the
whole sound system. If another task replies with a DeviceInUse message, then
its unique handle and (not-so unique) name will be displayed here. The text
field below will show the information string received from the other task
(typically an explanatory message).

  Because this message protocol (described in PRM volume 3) predates the 16
bit sound system, it is unclear whether tasks that claim the linear handler
should respond to such DeviceClaim messages. Acorn should perhaps have
allocated a different device number for 16 bit sound, since it is largely
independent of the emulated 8 bit channels (although the configured sample
rate affects both).

  In my experience, the device claim protocol is much underused. For example
Acorn's own application 'Maestro' should rebuff attempts to claim device 6.0
when it is playing music, but it does not.

  Below are displayed the contents of the Scheduler and Channel Handler
blocks (as returned by SWI Sound_Configure) as well as the current 16 bit
linear handler. You should be able to tell from this information whether key
components of the sound system have become disconnected or been superseded
(for example by a tracker music player).

  Here, the Channel Handler is entitled '8 bit -law handler' because most
modules that replace it do so in order to talk directly to the DMA handler,
and do not provide facilities that are remotely similar.

  Currently on RISC OS the default 8 bit -law handler is the 'SoundChannels'
module, the default 16 bit linear handler (if any) is the 'SharedSound'
module and the default Scheduler is the 'SoundScheduler' module.

  Opposite the address of each sound system component a description will be
displayed. This is in two parts - a mnemonic to tell you what kind of memory
the address lies within and then the human-readable name of the area in
question. Bazound can identify addresses that lie within a relocatable
module ('RM'), the workspace for a given module instantiation ('WS') or a
dynamic area ('DA'). This last feature relies upon having RISC OS version
3.5 or later, and the dynamic area in question being contiguous rather than
sparse. For a workspace both module name and instantiation postfix will be
displayed (in the same format as the output from *Modules).

-----------------------------------------------------------------------------
6   Sound DMA handler dialogue box
    ==============================

  The DMA handler is implemented as the 'SoundDMA' module. This deals
directly with the sound hardware, responds to sound interrupts, and manages
the DMA buffers in which samples are stored prior to output. When necessary
it calls the channel handler to fill the DMA buffer with 8 bit -law samples
and also (on machines with appropriate hardware) calls the linear handler to
overwrite or merge 16 bit linear samples with this data.

  The three option buttons at the top of this dialogue box allow you to
enable or disable the sound system, the internal speaker (if allowed) and
oversampling (if supported). When the sound system is disabled all
associated interrupts and DMA activity ceases. The 'Speaker' option may not
work as expected on machines where the internal speaker is automatically
disabled while the headphone socket is in use. Oversampling was introduced
in RISC OS 3.6 and attempts to reduce undesirable high-pitched noise by
performing linear interpolation at sample rates up to 25kHz.

  Below these options are two sample rate selectors, one of which will be
faded. On machines with 16 bit sound the sample rate in Hz must be chosen
from those listed on the pop-up menu, because only a limited number
of sample rates are supported. On machines with 8 bit sound the sample
period in s may be altered by editing the value in the writable field or in
steps of 1 s by using the adjacent bump arrows. If you change one of these
values then the other will be updated in parallel.

  If you have the 'RateTracker' module loaded then the sample rate may be
reconfigured whilst this dialogue box is open without it being reflected in
the displayed settings. This module automatically controls the sample rate
and there is little point trying to fight it.

  The DMA buffer size is specified in terms of the number of samples per
channel. This value may be altered by editing the value in the writable
field or in steps of 1 sample by using the adjacent bump arrows. The buffer
size in bytes also depends on the number of channels and whether the samples
are 8 bit or 16 bit.

  The number of 8 bit -law channels (1, 2, 4 or 8) may be selected from a
pop-up menu. This is controlled by the DMA handler rather than the channel
handler because it affects the required format of the buffer (samples for
different channels must be interleaved) and use of the stereo image
registers.

  The stereo position for each of the 8 bit channels may be altered by
dragging the relevant slider (as labelled on its left side) or more
accurately by editing the value in the associated writable field. If less
than 8 channels are configured then the remaining stereo positions will be
shown faded but updated in tandem (this reflects the operation of SWI
Sound_Stereo).

-----------------------------------------------------------------------------
7   Sound channel handler dialogue box
    ==================================

  The default channel handler is the 'SoundChannels' module. This provides a
facility for voice generators (such as the 'WaveSynth' module) to be
registered and associated with a given channel. For each channel it
maintains a record of the volume, voice, pitch and timbre. It also maintains
a logarithmic volume scale table which is used by voice generators that
respect the overall volume setting. When the DMA handler requests a buffer
fill the channel handler calls the appropriate voice generators in turn.

  The overall volume may be changed by dragging the slider at the top of
this dialogue box or by editing the value in the adjacent writable field. A
change of 16 will halve or double the volume.

  The overall tuning may be altered by editing the value in the relevant
writable field, or in steps of 1 by the adjacent bump arrows. This value is
in the raw integer format used internally (4096ths of an octave). The
equivalent number of semitones from the default tuning value of 27312 is
displayed below in a more human readable form (as a signed fractional value
to six decimal places).

  Remember that settings within this dialogue box will not affect 16 bit
sound output or any tracker music player (or similar) that supersedes the
default channel handler.

-----------------------------------------------------------------------------
8   Sound scheduler dialogue box
    ============================

  The default scheduler is the 'SoundScheduler' module. This allows SWIs
(usually Sound_ControlPacked) to be queued and called after a chosen time
interval. This period may be measured from when a SWI is scheduled or in
beats from the start of the last bar. To this end a beat counter is provided
which repeatedly counts upward from 0 to (bar length-1). Both the bar length
and tempo (frequency of beat counter increment) are configurable.

  The tempo may be altered by editing the value in the writable field or in
steps of 1 by the adjacent bump arrows. This is in the raw integer format
used internally (beats per 4096th of a second). The equivalent number of
beats per second is displayed below in a more human readable form (as a
fractional value to six decimal places).

  The beat counter may be enabled or disabled by clicking the associated
option button. When the beat counter is enabled, the bar length may be set
by editing the value in the writable field below or by using the adjacent
bump arrows.

  Remember that settings within this dialogue box only affect programs that
use the scheduler - for example the 'Maestro' application bundled with most
RISC OS computers.

-----------------------------------------------------------------------------
9   Reinitialise sub-menu
    =====================

  The 'Reinitialise' sub-menu (of the iconbar menu) allows you to reset
various modules that are standard components of the RISC OS sound system
(equivalent to entering *RMReInit <moduletitle> at the command line).

  Reinitialising the 'SoundDMA' module will cause it to forget the current
8 bit -law handler, 16 bit linear handler and scheduler. Whether they are
re-registered depends upon whether they respond to service call &54; older
versions of the 'SoundChannels', 'SharedSound' and 'SoundScheduler' modules
do not. Nor do any known third-party modules.

  Reinitialising the 'SoundChannels' module will cause it to forget all voice
generators. Whether they are re-installed depends upon whether they respond
to service call &54; older versions of 'WaveSynth', 'StringLib' and
'Percussion' modules do not. Nor do any known third-party modules.

  Selecting 'All of the above' will reinitialise the named modules in the
listed order. This is a quick and dirty way of restoring the default state
of the sound system that should work even on machines where components do
not re-register automatically.

-----------------------------------------------------------------------------
10  Program history
    ===============

0.01 (18 Aug 2003)
   First version.

0.02 (21 Aug 2003)
   Added this help text, accessible via new 'Help...' menu entry or F1 key
    shortcut in the dialogue box.
   Implemented Return and Escape key shortcuts for the dbox action buttons.

0.03 (23 Aug 2003)
   Moved informational displays from main dbox into new window. The contents
    of the Scheduler and Channel Handler blocks are now decoded and
    displayed. Parameter to linear handler is displayed, in addition to code
    address.
   Slightly more efficient use of memory.
   Now sets the 'Oversampling' option from the current state, rather than
    the configured default as we had been erroneously doing.
   Renamed application 'Bazound'.

0.04 (25 Aug 2003)
   Fixed stupid module version numbers in RMEnsure file.

0.05 (14 Sep 2003)
   Fixed stupid !Wimp file, which had been in the wrong format. This
    resulted in Bazound wasting time by constantly demanding null polls.

0.06 (21 Sep 2003)
   Reduced the maximum amount of memory requested in the !Run file, which
    was unnecessarily high (accidentally left from debuggging).

0.07 (12 Jan 2004)
   Corrected order of dbox writable fields, for caret movement (e.g. TAB).
   Minor changes to sound hardware type description strings and associated
    documentation.
   ResFind is now used to locate appropriate Messages and Resource files
    for the user's country (was previously used only for Help file).
   Use of the application name 'Bazound' is now officially registered.

0.08 (08 Aug 2004)
   Added lots of extra information to the display in the info window, which
    has expanded to three columns wide. Bazound can now identify whether
    a given address lies within a module or its workspace. Hitherto this
    required the aid of an external utility such as '*addr' or '*where'.
   Took advantage of the extra width of the info window to make the
    sound hardware descriptions more verbose.
   By default, the sound configuration dbox and info window now open with
    the options / information for the Scheduler hidden, because the
    Scheduler is rarely used by modern applications.
   Updated to build with version 2.02 of AppBasic (hence ResFind is no
    longer used).

0.09 (03 Sep 2004)
   In the info window, 'Code' is now displayed next to the module name when
    an address is found to lie within the code (read only) area of a module.
    Previously the name of the first instantiation of that module would be
    displayed, which was rather arbitrary.

0.10 (22 Oct 2004)
   If a given address does not lie within any module or workspace then
    Bazound will now report which dynamic area it is within.
   Redesigned the info window to effectively support this feature - instead
    of an 'Instance' field for each address the instantiation name (if any)
    is now postfixed to the module name and new 2 letter code shows what kind
    of memory area the description refers to.

0.11 (22 Oct 2004)
   Renamed the '8 bit -law sound' group box 'Channel handler' to reflect
    the fact that the options within are specific to the SoundChannels
    module only. Moved the 'No. of channels' selector out of this box
    because it is handled by the SoundDMA module.

0.12 (11 Feb 2005)
   Reduced the maximum amount of memory requested in the !Run file, which
    was unnecessarily high (accidentally left from debuggging).
   Corrected mistake in error message used in absence of BorderUtils module.

0.13 (07 May 2005)
   Corrected bounds on input of buffer size, tuning and tempo values; it
    had been possible to enter '0' (meaning 'read value', hence no effect).
   Added display of tuning and tempo values as decimal fractions to aid
    interpretation of the raw integer values used within the sound
    configuration dbox.
   Finally added proper application icons (both high and low resolution
    variants).
   Added editable numeric display of current volume setting in addition to
    slider.

0.14 (06 Jun 2005)
   Fixed bug where the mnemonic for the linear handler code address could
    be displayed in place of the name of the memory containing the
    associated parameter. This only manifested when a handler had -1 as its
    parameter.
   Now recognises when channel handler or scheduler become detached
    (signified by a non-word aligned address) and validates other addresses
    to guard against data aborts when reading from C.H. or scheduler block.
   Tweaked mnemonics used to describe different types of memory area.

0.20 (15 Oct 2005)
   Added a 'Sound status' window that displays the current sound system
    status in real time.
   Divided the old 'Sound configuration' dialogue box into three separate
    dialogue boxes; one for each component of the sound system. This
    eliminates the need for a scrolling window with a button bar.
   Dialogue boxes now open centred on the screen. Information windows open
    at last screen position, as before.
   User can now view and configure the stereo positions for the 8 bit
    channels.
   User can now enable or disable the scheduler's beat counter and set the
    bar length.

0.21 (21 Oct 2005)
   Fixed bug in version 0.20 where no event mask was passed to SWI Wimp_Poll
    and hence key pressed events were being swallowed. This manifested as
    failure of F12 and other global hot keys when Bazound windows were open.

0.22 (15 Jan 2006)
   Fixed backward gadget linkage from channel 1 stereo position to buffer
    size (in Sound DMA handler dialogue box).

0.23 (18 Feb 2006)
   'Sound system components' window is now updated automatically in real
    time rather than requiring manual refreshes. Have therefore removed the
    'Refresh display' menu entry.
   Fixed longstanding bug where bits 0-1 of the value returned in R0 from
    SWI Sound_Mode 0 was interpreted as the hardware type, instead of bits
    0-3 of R1. Hence '...external clock (DAC clock is slave)' was always
    reported on machines with 16-bit sound.
   The 'Sound status' window now displays an indication of whether
    oversampling is enabled or not, and we no longer momentarily disable
    oversampling upon setting up the 'DMA handler' dialogue box.
   Added 'Reinitialise' sub-menu to allow the sound system to be reset
    without recourse to the command line and *RMReInit.
   Made this help text available from a menu on the 'Sound status' window.
   Added very limited interactive help.

0.30 (24 Mar 2007)
   New 'Device claimant' section of the 'Sound system components' window
    shows which Wimp task (if any) currently claims ownership of the sound
    system.
   For convenience, linked the 'Configure' and 'Reinitialise' sub-menus into
    the menu of the 'Sound system components' and 'Sound status' windows.
   Moved two items of the iconbar menu to a new sub-menu 'Show'.

0.31 (24 Mar 2007)
   Minor fix to prevent hiccup when the monotonic timer value wraps from
    positive to negative (which happens 35 weeks and 3 days after reset).

0.32 (24 Mar 2007)
   The human-readable form of the channel handler's tuning value is now
    displayed as a signed no. of semitones relative to the default value of
    27312. Previously the default value appeared unhelpfully as 80.015625.

0.33 (08 Apr 2007)
   Added a picture of a speaker to the application icon and gave it an
    irregular outline to make clear that it isn't a file icon (as per the
    RISC OS 3 Style Guide). Previously, the size and square border could
    have given the wrong impression.
   Corrected the name of the low resolution version of the small application
    icon (which was never used because it was erroneously named 'export').
   Added a new icon for use when Bazound windows are iconised.

0.34 (07 Oct 2007)
   Modified for compatibility with version 3.02 of AppBasic (with a few
    minor tweaks).
   Fixed a bug where the definition of PROCbroadcast_claim was terminated by
    ENDIF rather than ENDPROC. I can hardly believe this didn't cause noticeable
    problems before (presumably because the following procedure in the
    compressed !RunImage was relatively benign).

-----------------------------------------------------------------------------
11  Ideas for improvements
    ======================

   Provide a facility to list currently installed SharedSound handlers.
   Provide a facility to list currently installed voice generators.
   Add a real-time display of the status of each 8 bit channel (using SWI
    Sound_ReadControlBlock).

-----------------------------------------------------------------------------
12  Licence and Disclaimer
    ======================

  This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public Licence as published by the Free
Software Foundation; either version 2 of the Licence, or (at your option)
any later version.

  This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licence for
more details.

  You should have received a copy of the GNU General Public Licence along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.

  If you did not receive source code with this program then you can download
it from http://kingfishercorner.eu . To rebuild the program you
will also need the BASIC libraries supplied with AppBasic. I used version
3.02 of AppBasic; modification to the program may be required to make it
build with other versions.

-----------------------------------------------------------------------------
13  Credits
    =======

  Bazound was designed and programmed by Christopher Bazley.

  AppBasic is (C) Joe Taylor. It is available from
  http://www.jettons.co.uk/riscos/toolbox/

  The application icon is based on a design by Martin Bazley.

  The application name "Bazound" (including associated sprites/system
variables) has been officially registered with RISCOS Ltd.

-----------------------------------------------------------------------------
14  Contact details
    ===============

  Feel free to contact me with any bug reports, suggestions or anything else.

  Mail:  Mr C.J. Bazley
         139 Church End
         Cambridge
         CB1 3LF

  Email: mailto:cs99cjb@gmail.com

  WWW:   http://kingfishercorner.eu
